TRANSFORM Function
Syntax
Arguments
- value
An expression. Any type
- formatting_string
A character string containing format codes and/or template characters.
Description
Returns a character string that formats a user defined expression.
Discussion
TRANSFORM() returns a formatted character string containing the specified Expression modified according to the instructions of the Formatting_String. TRANSFORM() returns a character string regardless of the data type the Expression returns. This function provides an extremely flexible method for formatting data for output. There are many built-in formatting options that you can select when you place a field on a layout. If these formatting options do not suit your needs, you can use TRANSFORM() to create your own customized options. For example, if you have a field called COMPANY, you can format it to print in capitals with a space between each letter (e.g., "A L P H A S O F T W A R E"). To do this, define a calculated field using the following expression:
transform(COMPANY,"@!R X X X X X X X X X X X X X X X")
You can then place this calculated field on a report layout in place of the COMPANY field.
Formatting Strings
TRANSFORM() formats the input expression based on the formatting_string 's particular formatting codes and template characters. For example, the expression TRANSFORM(AMOUNT,"@$(") uses the formatting string "@$(". It returns a string with the number in AMOUNT formatted with a leading dollar sign ($), and with negative numbers enclosed in parentheses (e.g., -234.23 -> ($234.23) ). The formatting string contains the "$" and the "(" formatting codes. The "@" indicates that the characters that follow should be treated as formatting codes and not template characters. The expression TRANSFORM(AMOUNT,"$$$,$$$.99") uses the formatting string "$$$,$$$.99". It returns a string with the number in AMOUNT formatted with two decimal places, thousands separated by commas, and a leading spaces $ sign (e.g., $2,234.12). In this case, the formatting string contains a template, "$$$,$$$.99". You can combine formatting codes and template strings in the same formatting string. for Example:
transform(AMOUNT,"@( $$$,$$$.99")
If a formatting string contains both formatting codes and a template, the formatting codes, prefixed with "@", must be at the start of the formatting string. A space must separate the formatting codes and the template. The following sections describe the various formatting codes and template characters that Alpha Anywhere allows in the formatting string.
Format Codes
Format codes must be preceded with the "@" character. Otherwise Alpha Anywhere assumes that the format characters are part of a template. The following are the various formatting codes:
- Format Code
- Description
- !
Converts letters to uppercase.
- ^
(carat symbol) Displays numbers in scientific notation.
- $
Displays data in the currency format.
- (
Displays negative numbers enclosed in parentheses.
- B
Left-aligns text.
- C
Displays CR (credit) after positive numbers.
- D
Displays dates using the current date format (MM/DD/YYYY or DD/MM/YYYY), as Determined by your Windows setting.
- E
Displays dates using the European date format (DD/MM/YYYY).
- I
Centers text.
- J
Right-aligns text.
- L
Displays leading zeros.
- R
Used in conjunction with a template string. Directs Alpha Anywhere to display a character value with template characters inserted at the appropriate places (e.g., displays a phone number, 2125551212 as (212) 555-1212)).
- T
Trims leading and trailing blanks from a field.
- X
Displays DB (debit) after negative numbers.
- Z
Displays a zero numeric value as a blank string.
You can combine formatting functions. For example, @CX displays "DB" after negative numbers and "CR" after positive numbers.
More on the R Formatting Code
This section gives a more complete explanation of how the @R formatting code works in conjunction with a template by describing how the following expression works:
TRANSFORM(PHONE,"@R (999) 999-9999")
Assume that PHONE contains "2134567890".
- 1
Start with the first character in the template string ("("). If the character is a special template symbol (e.g., #, 9, A, N, X, !, L, Y), output the first character from PHONE. Otherwise, output the template character. Since "(" is not a template symbol, at this stage, the output string is "(".
- 2
Move to the second character in the template string ("9"). Since this character is a template symbol, get a character from PHONE ("2"). At this stage, the output string is "(2".
- 3
Move to the third character in the template string ("9"). Since this character is a template symbol, get the next character from PHONE ("1"). At this stage, the output string is "(21".
- 4
Move to the fourth template character ("9"). Since this is a template symbol, get the next character from PHONE ("3"). The output string is "(213".
- 5
Move to the fifth template character (")"). This is not a template symbol; therefore, output the template character rather than the next character from PHONE. The output string is now "(213)".
- 6
Move to the sixth template character (a space). Since this is not a template symbol, output the template character "(213) ".
- 7
Move to the seventh template character ("9"). Since this is a template symbol, output the next character in PHONE "(213) 4".
- 8
Continue with the eighth and ninth template characters. They are both template symbols, so the output string is now "(213) 456".
- 9
The tenth template character is "-". It is not a template symbol, so the output string is now "(213) 456-".
- 10
The remaining template characters are template symbols, so the remaining characters in PHONE are output. The complete output string is "(213) 456-7890".
Note : If the TRANSFORM expression for PHONE does not include the @R formatting code (e.g., TRANSFORM(PHONE,"(999) 999-9999")), the output string is "(123) 789-". Without the "@R" formatting code, Alpha Anywhere outputs either the template character or the corresponding character from the input expression.
Template Characters
A template is a character string with a single symbol for each character in the field. Some characters have a special meaning when used as Part of a template. Templates are frequently used in conjunction with the "R" formatting code. The following are the various template characters:
- Template Character
- Meaning
- 9
Outputs the next character from the input expression.
- #
Outputs the next character from the input expression.
- A
Outputs the next character from the input expression.
- N
Outputs the next character from the input expression.
- Y
Outputs the next character from the input expression and converts it to "Y" if the character is "T" or "Y"; otherwise converts it to "N".
- L
Outputs the next character from the input expression and converts it to "T" if the character is "T" or "Y"; otherwise converts it to "F".
- X
Outputs the next character from the input expression.
- !
Outputs the next character from the input expression and transforms it to uppercase.
- other
Use the R function if you include any other characters in a template.
You can use four other symbols in templates for numbers:
- Character
- Meaning
- .
Separates integers and decimals with the decimal character.
- ,
Separates thousands with the thousands separator.
- *
Displays asterisks in place of leading zeros.
- $
Displays the currency symbol.
Format Examples
transform("alpha software", "@!") -> "ALPHA SOFTWARE"
transform(AMOUNT, "@t($")-> ($2123.12), assuming AMOUNT contains -2123.12
transform(AMOUNT, "@t( $$$,$$$.99") -> ($2,123.45) assuming AMOUNT contains -2123.12
transform("ALPHA", "@R X X X X X X X X X X X X X X X") -> "A L P H A"
transform("ALPHA", "@R X-X-X-X-X-X-X-X-X-X-X-X-X-X-X") -> "A-L-P-H-A"
transform("2125551212", "@R (999) 999-9999") ? "(212) 555-1212"Template Examples
transform("alpha", "!AAAAAAAAAA") -> "Alpha"
transform("10/25/92", "99-99-99") -> "10-25-92"
transform(2341.2312, "$$$,$$$.99") -> " $2,341.23"
transform(2341.2312, "***,***.99") -> "**2,341.23"See Also